<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>
  File: README
  
    &mdash; Documentation by YARD 0.8.2.1
  
</title>

  <link rel="stylesheet" href="css/style.css" type="text/css" media="screen" charset="utf-8" />

  <link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />

<script type="text/javascript" charset="utf-8">
  hasFrames = window.top.frames.main ? true : false;
  relpath = '';
  framesUrl = "frames.html#!" + escape(window.location.href);
</script>


  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>

  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>


  </head>
  <body>
    <div id="header">
      <div id="menu">
  
    <a href="_index.html">Index</a> &raquo; 
    <span class="title">File: README</span>
  

  <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
</div>

      <div id="search">
  
    <a class="full_list_link" id="class_list_link"
        href="class_list.html">
      Class List
    </a>
  
    <a class="full_list_link" id="method_list_link"
        href="method_list.html">
      Method List
    </a>
  
    <a class="full_list_link" id="file_list_link"
        href="file_list.html">
      File List
    </a>
  
</div>
      <div class="clear"></div>
    </div>

    <iframe id="search_frame"></iframe>

    <div id="content"><div id='filecontents'><h1><a href="http://github.com/zamith/citygate"><img style="max-width:100%;width: 36%;float: left;" src="http://i50.tinypic.com/wag4d4.png"></a> <a href="http://travis-ci.org/zamith/citygate"><img src="https://secure.travis-ci.org/zamith/citygate.png" /></a></h1>
<p>
Citygate is a rails engine that provides your application with user
authentication (on the site or through facebook or google) using Devise and
fully customizable authorization using CanCan.
</p>
<p>
It also provides a customizable backend for administrating all your users,
using pjax and pushState making your website as fast as responsive as you
ever wanted it to be.
</p>
<h2>Instalation</h2>
<p>
First add the gem to your Gemfile to get the latest stable version
</p>
<pre class="code ruby"><code>
  <span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>citygate</span><span class='tstring_end'>&quot;</span></span>
</code></pre>
<p>
or go on the edge with
</p>
<pre class="code ruby"><code>
  <span class='id identifier rubyid_gem'>gem</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>citygate</span><span class='tstring_end'>&quot;</span></span><span class='comma'>,</span> <span class='symbol'>:git</span> <span class='op'>=&gt;</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>https://zamith@github.com/zamith/citygate.git</span><span class='tstring_end'>&quot;</span></span>
</code></pre>
<h2>Database Configuration</h2>
<p>
In order to get the database ready to run citygate you will need to fetch
the migrations
</p>
<pre class="code ruby"><code>
  rake citygate:install:migrations
</code></pre>
<p>
and run them
</p>
<pre class="code ruby"><code>
  <span class='id identifier rubyid_rake'>rake</span> <span class='label'>db:</span><span class='id identifier rubyid_migrate'>migrate</span>
</code></pre>
<p>
then drop this line at your <tt>db/seeds.rb</tt> file in order to be able
to populate the db with the needed records
</p>
<pre class="code ruby"><code>
  <span class='const'>Citygate</span><span class='op'>::</span><span class='const'>Engine</span><span class='period'>.</span><span class='id identifier rubyid_load_seed'>load_seed</span>
</code></pre>
<p>
and finally run the seeds command to actually populate the db
</p>
<pre class="code ruby"><code>
  <span class='id identifier rubyid_rake'>rake</span> <span class='label'>db:</span><span class='id identifier rubyid_seed'>seed</span>
</code></pre>
<h2>Routes Configuration</h2>
<p>
To get all the citygate routes working you just need to mount them by
adding the following line to your <tt>config/routes.rb</tt> file
</p>
<pre class="code ruby"><code>
  <span class='id identifier rubyid_mount'>mount</span> <span class='const'>Citygate</span><span class='op'>::</span><span class='const'>Engine</span> <span class='op'>=&gt;</span> <span class='tstring'><span class='tstring_beg'>&quot;</span><span class='tstring_content'>/</span><span class='tstring_end'>&quot;</span></span>
</code></pre>
<h2>Environment Configuration</h2>
<p>
Since citygate will send confirmation emails to any user that signs up, you
will need to have your email configured.
</p>
<p>
In case of development add this to
<tt>config/environments/development.rb</tt>
</p>
<pre class="code ruby"><code>
  <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_action_mailer'>action_mailer</span><span class='period'>.</span><span class='id identifier rubyid_default_url_options'>default_url_options</span> <span class='op'>=</span> <span class='lbrace'>{</span> <span class='symbol'>:host</span> <span class='op'>=&gt;</span> <span class='tstring'><span class='tstring_beg'>'</span><span class='tstring_content'>localhost:3000</span><span class='tstring_end'>'</span></span> <span class='rbrace'>}</span>
</code></pre>
<h2>Helper Configuration</h2>
<p>
In order to get the helper methods citygate exposes you&#8217;ll have to
include them in your <tt>app/controllers/application_controller.rb</tt>
like so:
</p>
<pre class="code ruby"><code>
  <span class='kw'>class</span> <span class='const'>ApplicationController</span> <span class='op'>&lt;</span> <span class='const'>ActionController</span><span class='op'>::</span><span class='const'>Base</span>
    <span class='id identifier rubyid_helper'>helper</span> <span class='const'>Citygate</span><span class='op'>::</span><span class='const'>Engine</span><span class='period'>.</span><span class='id identifier rubyid_helpers'>helpers</span>
  <span class='kw'>end</span>
</code></pre>
<p>
The exposed methods are:
</p>
<table>
<tr><td valign="top">role_changer</td><td><p>
a select for changing roles (only available when logged in and in
development)
</p>
</td></tr>
<tr><td valign="top">citygate_nav_links</td><td><p>
the default <tt>nav</tt> for citygate with sign in, log out and admin links
</p>
</td></tr>
</table>
<h2>OmniAuth Configuration</h2>
<p>
Citygate needs your facebook apps identifiers which are loaded from a file
you must create called <tt>config/accounts.yml</tt> and has the following
format:
</p>
<pre class="code ruby"><code>
  facebook:
    app_id: &quot;your app id from https://developers.facebook.com/apps&quot;
    app_secret: &quot;your app secret from https://developers.facebook.com/apps&quot;
</code></pre>
<p>
This file is not required for the application to run, but without it the
facebook login will not work.
</p>
<p>
In case you are wondering, the reason it is not required for you to add
your google OAuth identifier is because it is the same for everyone. It
then redirects you to a authentication service within google servers.
</p>
<h2>Loading Assets</h2>
<p>
In order to have the javascript added by Citygate you need to include it in
your manifest file, like so:
</p>
<pre class="code ruby"><code>
  //= require citygate
</code></pre>
<h2>Citygate Options</h2>
<p>
You can change citygate&#8217;s defaults by editing your
<tt>config/application.rb</tt> file like so
</p>
<pre class="code ruby"><code>
  <span class='const'>Citygate</span><span class='op'>::</span><span class='const'>Engine</span><span class='period'>.</span><span class='id identifier rubyid_configure'>configure</span> <span class='kw'>do</span>
    <span class='id identifier rubyid_config'>config</span><span class='period'>.</span><span class='id identifier rubyid_option'>option</span> <span class='op'>=</span> <span class='id identifier rubyid_value'>value</span>
  <span class='kw'>end</span>
</code></pre>
<h3>Options</h3>
<p>
The available options are:
</p>
<table>
<tr><td valign="top">will_paginate_options</td><td><p>
an hash with any option supported by <a
href="https://github.com/mislav/will_paginate/wiki">paginate</a>
</p>
</td></tr>
<tr><td valign="top">mount_path</td><td><p>
if you mount the engine in any other path than &#8220;/&#8221;, must define
it here as well so that omniauth can be aware of it
</p>
</td></tr>
<tr><td valign="top">no_of_users</td><td><p>
limit the number of users allowed in your system
</p>
</td></tr>
</table>
<h2>Running Citygate</h2>
<p>
Users in citygate will not be able to login with their google account if
you use WEBrick, due to its url length limitation. Therefore run your
server in development with <tt>rails s thin</tt>, to run the thin server.
</p>
<hr style="height: 1px"></hr><p>
<b>Note:</b> Do not forget to check the routes made available to you by
Citygate with <tt>rake routes</tt> and to take a look at the doc at <a
href="http://rubydoc.info/github/zamith/citygate/master/frames">RubyDoc</a>
</p>
</div></div>

    <div id="footer">
  Generated on Thu Sep 20 15:56:36 2012 by
  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
  0.8.2.1 (ruby-1.9.2).
</div>

  </body>
</html>